---
title: Combobox
description: An input combined with a list of predefined items to select.

links:
  doc: https://base-ui.com/react/components/combobox#api-reference
---

<ComponentPreview name="p-combobox-1" />

## Installation

<CodeTabs>

<TabsList>
  <TabsTab value="cli">CLI</TabsTab>
  <TabsTab value="manual">Manual</TabsTab>
</TabsList>

<TabsPanel value="cli">

```bash
npx shadcn@latest add @coss/combobox
```

</TabsPanel>

<TabsPanel value="manual">

<Steps>

<Step>Install the following dependencies:</Step>

```bash
npm install @base-ui-components/react
```

<Step>Copy and paste the following code into your project.</Step>

<ComponentSource name="combobox" title="components/ui/combobox.tsx" />

<Step>Update the import paths to match your project setup.</Step>

</Steps>

</TabsPanel>

</CodeTabs>

## Usage

### Single Selection

```tsx
import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from "@/components/ui/combobox"
```

```tsx
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items}>
  <ComboboxInput placeholder="Select an item..." />
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item.value} value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

### Multiple Selection

```tsx
import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxValue,
} from "@/components/ui/combobox"
```

```tsx
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items} multiple>
  <ComboboxChips>
    <ComboboxValue>
      {(value: { value: string; label: string }[]) => (
        <>
          {value?.map((item) => (
            <ComboboxChip key={item.value} aria-label={item.value}>
              {item.label}
            </ComboboxChip>
          ))}
          <ComboboxInput
            placeholder={value.length > 0 ? undefined : "Select a Select an item..."}
            aria-label="Select an item"
          />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>
```

## API Reference

The `ComboboxInput` component extends the original Base UI component with a few extra props:

| Prop          | Type                        | Default     | Description                                                                                      |
| ------------- | --------------------------- | ----------- | ------------------------------------------------------------------------------------------------ |
| `size`        | `"sm" \| "default" \| "lg"` | `"default"` | The size variant of the input field.                                                             |
| `showTrigger` | `boolean`                   | `true`      | Whether to display a trigger button (chevron icon) on the right side of the input.               |
| `showClear`   | `boolean`                   | `false`     | Whether to display a clear button (X icon) on the right side of the input when there is a value. |

## Examples

### Disabled

<ComponentPreview name="p-combobox-2" />

### Small Size

<ComponentPreview name="p-combobox-3" />

### Large Size

<ComponentPreview name="p-combobox-4" />

### With Label

<ComponentPreview name="p-combobox-5" />

### Auto Highlight

Automatically highlight the first matching option.

<ComponentPreview name="p-combobox-6" />

### With Clear Button

<ComponentPreview name="p-combobox-7" />

### With Groups

<ComponentPreview name="p-combobox-8" />

### With Multiple Selection

<ComponentPreview name="p-combobox-9" />

### With Input Inside Popup

<ComponentPreview name="p-combobox-10" />

### Form Integration

<ComponentPreview name="p-combobox-11" />

### Form Integration - Multiple

<ComponentPreview name="p-combobox-12" />
